home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / autodox2.zip / MANUAL.DOC < prev    next >
Text File  |  1992-07-18  |  8KB  |  301 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                AutoDOX v2.00
  17.  
  18.             Copyright (c) 1992, TDM Software - ALL RIGHTS RESERVED
  19.  
  20.                      Designed & Written by Chris Hettinger
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.                                   Page 1
  58.  
  59.      AutoDox v2.00 Copyright (c) 1992 TDM Software - ALL RIGHTS RESERVED
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.    DISCLAIMER
  67.  
  68.      Users of AutoDOX must accept this disclaimer of warranty:
  69.      "AutoDOX is supplied as is.  The author disclaims all warranties,
  70.      expressed or implied, including, without limitation, the warranties
  71.      of merchantability and of fitness for any purpose.  The author
  72.      assumes no liability for damages, direct or consequential, which
  73.      may result from the use of AutoDOX."
  74.  
  75.    SHAREWARE AGREEMENT
  76.  
  77.      AutoDOX is a "shareware program" and is initially provided at no
  78.      charge.  Feel free to share it with your friends, but please do
  79.      not give it away altered or as part of another system.  Anyone
  80.      distributing AutoDOX for any kind of remuneration must first
  81.      contact TDM at the address listed below for authorization.
  82.      This authorization will be automatically granted to distributors
  83.      recognized by the (ASP) as adhering to its guidelines for
  84.      shareware distributors, and such distributors may begin offering
  85.      AutoDOX immediately; however, TDM must still be advised so that
  86.      the distributor can be kept up-to-date with the latest version of
  87.      AutoDOX.
  88.  
  89.      If you like AutoDox and would like to remain using it, send the
  90.      enclosed registration form (REGISTER.FRM), and $25 to the following
  91.      address:
  92.  
  93.                      TDM Software  c/o  Chris Hettinger
  94.                      3054 Pritchard Hall - East
  95.                      Va. Tech
  96.                      Blacksburg, VA.  24060-0023
  97.  
  98.      Fully commented source code for AutoDOX is available for $50.
  99.      This includes a royalty free license agreement and one year of
  100.      free upgrades.
  101.  
  102.    RELEASE HISTORY
  103.  
  104.      1.0      March 1992     Initial release, aimed at doing the busy work
  105.                              for my CompSci class at Tech
  106.  
  107.      2.0      July  1992     Second release, a more complete utility.  Now
  108.                              allows for input of procedure headers, and
  109.                              compiles lists of procedures.
  110.  
  111.    ACKNOWLEDGMENTS
  112.  
  113.      * Turbo Pascal is a registered trademark of Borland International
  114.      * MS-DOS is a registered trademark of Microsoft Corporation
  115.      * All other programs are (c) and/or (tm) by their respective
  116.        author unless otherwise noted
  117.  
  118.                                   Page 2
  119.  
  120.      AutoDox v2.00 Copyright (c) 1992 TDM Software - ALL RIGHTS RESERVED
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.    WHAT IS AUTODOX?
  128.  
  129.         AutoDox is a tool to assist you in the documentation of pascal source
  130.    code.  AutoDox can create procedure/function headers, or compile a list of
  131.    procedures in a given file.  After using AutoDOX, I believe you'll find it
  132.    as useful as I have.
  133.  
  134.         AutoDOX was originally written to defeat the menial commenting
  135.    tasks required by my computer science class.  Therefore, its main goal was
  136.    to save me time.  AutoDOX works best on a program that has a minimal
  137.    quantity of comments already coded.  It was meant to run on a file with
  138.    next to no comments, for those of us who like to write the whole program,
  139.    and document it when it is finished.
  140.  
  141.         The AutoDOX code is structured to best fit my programming style.
  142.    Since there is no way to create a program that would fit everyones needs,
  143.    I didn't try.  It is, however, quite flexible, and the programming
  144.    'restrictions' are minor, and will NOT impose a large effort on the
  145.    programmer's effort.  The 'restrictions' are listed on the next page.
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.                                   Page 3
  178.  
  179.      AutoDox v2.00 Copyright (c) 1992 TDM Software - ALL RIGHTS RESERVED
  180.  
  181.  
  182.  
  183.    USING AUTODOX. 'Code Restrictions'
  184.  
  185.  
  186.         Maybe restrictions is a harsh word.  AutoDOX will run on any code,
  187.    but may give undesired results if the following rules are not adhered to.
  188.    So if your unsure if your code will work, give it a try.  It may just
  189.    save you some time.
  190.  
  191.    Here are the restrictions --
  192.  
  193.    1.  The following words must be the first on their line, no commenting
  194.        may appear before them:
  195.                        UNIT, PROGRAM,
  196.                        FUNCTION, PROCEDURE
  197.  
  198.        Example:
  199.                      Program TEST;
  200.        Bad Example:
  201.                      (* This is my program *) Program Test;
  202.  
  203.  
  204.    2.  No comments should appear after a procedure header (on the same line),
  205.        or inside the passed parameter if you use the (* *) delimters.  When
  206.        a parameter list spans more than one line, AutoDOX checks for the ')'
  207.        on the following lines to find the end of the field.  Inline comments
  208.        using (* *) will confuse it. The second to last character at the end
  209.        of the field must be a ')'.
  210.  
  211.        Example:
  212.                     Procedure TEST(var A: integer;  {This is ok}
  213.                                     var B: real);
  214.                                                ^
  215.                                                This must be here.
  216.                                                No comments after it.
  217.        Bad Example:
  218.                     Procedure TEST(var A: integer;  (* This is bad  *)
  219.                                     var B: real);   (* Do not do it *)
  220.  
  221.    And thats about it.  Not very restricting as far as I'm concerned. And
  222.    the time you save is well worth the change.
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.                                   Page 4
  238.  
  239.      AutoDox v2.00 Copyright (c) 1992 TDM Software - ALL RIGHTS RESERVED
  240.  
  241.  
  242.  
  243.      USING AUTODOX. 'Documenting code, the specifics'
  244.  
  245.      AutoDOX is mostly self-explanatory. The only part that could cause
  246.      confusion is entering the comment field.
  247.  
  248.      When you choose to document a file, a screen with 15 lines appears.
  249.      What you enter will be tagged before every procedure/function in the
  250.      file you are documenting.
  251.  
  252.      There are two special commands that AutoDOX recognizes. They must be
  253.      entered alone on a line.
  254.  
  255.      1>   &E
  256.             This command shortens the length of the comment block.  That way
  257.             if you don't need 15 lines, AutoDOX will stop after it hits &E.
  258.  
  259.      2>   &P
  260.             This command enters the procedure/function name that is being
  261.             documented.  It copies the procedure header into the comment.
  262.             It will not use any of your remaining 14 lines, no matter how
  263.             many lines the header spans.
  264.  
  265.  
  266.    TRYING AUTODOX.
  267.  
  268.    Since AutoDOX asks you for the output filename, none of your files can be
  269.    overwritten.  So you can try it out right away without endangering your
  270.    files, or, for the nervous, ...
  271.  
  272.    A sample pascal file is included with this program.  It is called
  273.    sample.pas. Try using AutoDOX on it and see the results before trying it
  274.    on your source code if you do not trust the program.
  275.  
  276.  
  277.  
  278.    Don't forget to register your copy today.
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.                                   Page 5
  298.  
  299.      AutoDox v2.00 Copyright (c) 1992 TDM Software - ALL RIGHTS RESERVED
  300.  
  301.